/*
 * Licensed to Nanjing RedOrange Co. ltd (RedOrange) under one or more
 * contributor license agreements. See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * RedOrange licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations
 * under the License.
 */
package redora.rdo.api;

import java.util.Date;

/**
 * Implement automatic pagination for collections that are retrieved from the database.
 * We assume two things here:<br>
 * 1. you want to limit the collection size to avoid problems when a large amount of records are involved;<br>
 * 2. there will be an automatic form of pagination: ie when the user scrolls down a list, the list will be extended automatically.<br>
 * This will have a few consequences. Most important is you can not jump to the end of a list.
 * In order to get to the end of a list you need to retrieve all the records in the collection.
 * It is also not necessary to know how many records there actually exist, 
 * only the answer to the question if there are more records then there are retrieved so far.
 * <br>
 * 
 * @author jaap
 *
 */
public interface Scroll {
	/** Number of records per page, or better, per fetch */
	public int pageSize();
	/** First time when the query was accessed. Useful if you want to refresh the entire result set based on query age.*/
	public Date firstAccessed();
	/** Return the Scroll and result set metrics as a JSON string. */
	public String toJSON();
	
	public void setPageSize(int pageSize);
	/** 
	 * In the implementation this is usually determined by secretly fetching one more record then pageSize.
	 * This method is not guaranteed because the underlying table can have been changed.
	 *  
	 * @return True If there are more records to be expected. 
	 */
	public boolean hasMoreRecords();
	/**
	 * Fetches the next page of records.
	 * @return True If new records were found.
	 */
	public boolean next();
	
	public void clear();
}
